Steal This CD

home *** CD-ROM | disk | FTP | other *** search

/ Steal This CD / steal_this_cd.iso / Chapter 07 - Where the Hackers Are / virc200.exe / {app} / ovs.txt < prev next >

Wrap

Text File | 2003-08-30 | 73KB | 1,336 lines

VSInterp Scripting Reference - ObjectVersus Jesse McGrew ObjectVersus (OVS) is a set of extensions to the Versus language that allow object-oriented programming and the creation and modification of user interface controls. OVS can be disabled by the host application. Concepts ======== An object is a data structure that combines data with code. Each object belongs to a class, or a family of objects with the same behavior. Each object that belongs to a class is called an instance of that class, and it can have different data from the other instances of the same class, but every instance of the same class has the same code. Pieces of code (commands and functions) associated with a class are called methods. Objects and classes exhibit three behaviors that are used in object-oriented programming: 1. Inheritance. One class can be based on (derived from) an existing class, and it inherits behavior from the existing class as well as having the ability to add its own behavior. The new class is called a child class or subclass, and the existing class is called the parent class or superclass. 2. Encapsulation. Instances of a class incorporate both data (properties) and code (methods). Typically, instead of operating on an object's data directly, outside callers call methods that cause the instance to operate on its own data. The implementation of the class's behavior is private to the class - the object can be used from outside without having to know how it does what it does. This allows the object's behavior to be rewritten while still using the same interface to the outside world. 3. Polymorphism. An object that looks like an instance of one class might actually be an instance of a subclass. Child classes can be used in place of their parent classes. Objects can have special types of properties called events, which contain code that the object will call whenever a certain action takes place. For example, a button object might have an event that it calls when the button is clicked. Where Classes Come From ======================= VSInterp gives access to several controls from Delphi's Visual Component Library (VCL). The host application can also define its own classes or expose VCL classes that are not exposed by VSInterp. Additionally, OVS scripts can define their own classes: see the Class..EndClass construct later in this document. Creating Objects ================ Objects are created with the $New() function: $New(<classname> <parameters>) This function returns a unique handle that identifies the instance. If the class is a visual component, <parameters> can take the form: [ownedby <owner-object>] [position <x>,<y>,<w>,<h>] where <owner-object> is the handle of the object that will own the new component; and <x>, <y>, <w>, and <h> are the left, top, width, and height of the new component, respectively. If the class is user-defined, <parameters> may be an arbitrary string that will be interpreted by the user-defined class. In other cases, <parameters> will be ignored and may be omitted. It's important to remember that $New() returns an object handle, not the object itself. If you use $New() and store the result in $MyObject, then display the contents with 'MessageBox $MyObject', you'll see a number, which is the index into an object table. If you delete the variable $MyObject with -@, the object won't be destroyed - you'll just forget its handle. If you assign a new value to $MyObject, even another object, the original object won't be destroyed. You must explicitly destroy it (see below). Destroying Objects ================== To destroy an object, use the Destroy command: Destroy $obj This deallocates the memory for the object. Any further use of the object handle should be harmless but may cause unexpected behavior. The Destroy command may cause errors or unpredictable behavior when used from one of the object's event handlers. In this case, use SafeDestroy instead. SafeDestroy will wait until the event handlers finish before destroying the object. Use code like this to destroy an object if it already exists before creating a new one: // check if $MyObject is a valid object handle if $IsObject($MyObject) Destroy $MyObject endif // create your object @ $MyObject = $new(TListBox ownedby 0) Setting Properties ================== To set a property of an object, use the @P command: @p $obj.PropName = Value The property must have been defined in the class specification. Properties can be treated like variables, but often setting a property (and less often, retrieving it) will cause something to happen. For example, setting a form's Caption property will cause the title bar of the form to change. Properties of VCL classes have associated data types, and attempting to set a property to a value of the wrong type may cause an exception to be thrown (see the section about exceptions later in this document). These types of properties are accessible from OVS: Boolean properties These can be set to 0 (false), 1 (true), or the strings "False" or "True". Integer properties These can only be set to a value that contains a valid number. Color properties These are actually a special type of integer properties. They can be set to an integer, a hex number in $$BBGGRR format, or a VCL color constant (see the section on VCL color constants later in this document). String properties These can be set to any value. Set properties These can be set to a string representation of the set (as used by the Versus set functions). For example, the BorderIcons property of a form might be set to [biSystemMenu,biMinimize]. Enumeration properties These can be set either to a string representing the enumeration value, or the integer index of the value. Enumerations are used when a property can only hold a few values which are each referred to by name: for example, the Align property can take the values alNone, alLeft, alRight, alTop, alBottom, and alClient. Object properties These can be set to a valid object handle, or the special value "nil" which indicates the absence of an object. Event properties These can be set to a command to run, or the special value "Nop" (as in "no operation") which indicates the absence of an event handler. Note that setting an event property to "Nop" does not set an empty event handler, it actually causes the event to be unhandled. Some components may distinguish between these two possibilities. To set an empty event handler--that is, to cause the event to be caught, but no action to be taken in response-- set the event property to an empty string. All properties of user-defined classes are string properties. Often the multiple-indirection syntax can be used, where the property of an object that it itself stored in a property is set: @p $form.Font.Color = clBlack This syntax is required when setting certain properties, since there is no way to retrieve $form.Font as a separate object. Retrieving Properties ===================== To retrieve a property of an object, use the $Prop() function: $Prop($obj.Prop) This returns the current value of the property. The multiple-indirection syntax works here as well: $Prop($form.Font.Color) Properties are returned slightly differently than they are set: Boolean properties Always returned one as the strings "True" or "False", never as an integer. Integer properties Returned as integers. Color properties Always returned as a decimal integer, never a hex number or VCL color constant. String properties Returned as strings. Set properties Returned as the string representation of sets: [biSystemMenu,biMinimize]. Enumeration properties Always returned as the string value, never the integer value. Object properties Retrieving a property never creates a new object handle. If there is no object stored in the property, "nil" will be returned. If the object stored in the property has been mapped, created by the script, or given an object handle by the host application, the handle will be returned. Otherwise, the string "<class>" will be returned, and the object will only be accessible through the multiple-indirection syntax, or with $mapprop(). Event properties If the property contains no event handler, "Nop" will be returned. If the property contains an event handling command that was set with OVS, the command will be returned. Otherwise, if the property contains an event handler that was set by the VCL or the host application (a handler written in compiled code, instead of script code), VSInterp will attempt to create and return a command that will call the compiled event handler. However, not all event types are supported this way, and for many event types the returned command will be useless and may cause exceptions or crash the application. This technique of creating a command to call a compiled event handler will only work for events that take a single parameter, Sender. These events are called notify events, and common events like OnClick, OnActivate, and OnResize are notify events. Calling Methods =============== Methods can be called as either commands or functions. To call a method as a command, write its handle, a period, and the method name, followed by the parameters: '$obj.MethodName arg1 arg2'. Any result from the method will be discarded. To call a method as a function, write its handle, a period, and the method name, followed by the parameters enclosed in parentheses (or a set of empty parentheses if there are no parameters): '$obj.MethodName(arg1 arg2)'. The function's return value will be the result of the method. Note that methods can only be called as functions when the object handle is in a variable. Writing Event Handlers ====================== To set an event handler on an object, use @P to set the event property of the object: @p $button.OnClick = MessageBox You clicked me! Certain variables are available to event handlers, depending on the type of the event. The variable $Sender, which holds the handle of the object that caused the event to run, is available to every type of event handler. These variables are available even when the event handler command is an alias call: @p $button.OnClick = _BUTTON_ONCLICK Alias _BUTTON_ONCLICK MessageBox You clicked the button marked $prop($Sender.Caption). EndAlias Note that the command in an event handler is not evaluated before it is run. If the command needs to be evaluated, put Eval before it: @p $button.OnClick = Eval MessageBox You clicked the button $$Sender. Especially note the use of two dollar signs: the right side of the statement is evaluated when the property is set, so $$Sender is used to prevent $Sender from being evaluated immediately. The Story Behind Exceptions =========================== The VCL or VSInterp might throw exceptions any time the script calls a method with invalid parameters, tries to create an object improperly, tries to destroy an object that has already been destroyed, or refers to an invalid method or property. When this happens, the rest of the enclosing routine will not be evaluated. If the exception occurs inside a function call, the result of the function call will be unpredictable but the routine that called the function will continue running. VCL Color Reference =================== These color constants are always the same on every system, because they represent a specific RGB color: clBlack, clMaroon, clGreen, clOlive, clNavy, clPurple, clTeal, clGray, clSilver, clRed, clLime, clBlue, clFuchsia, clAqua, clWhite. These color constants depend on the user's Windows settings, and represent color values that can be changed in Control Panel: clBackground Current color of the Windows background clActiveCaption Current color of the title bar of the active window clInactiveCaption Current color of the title bar of inactive windows clMenu Current background color of menus clWindow Current background color of windows clWindowFrame Current color of window frames clMenuText Current color of text on menus clWindowText Current color of text in windows clCaptionText Current color of the text on the title bar of the active window clActiveBorder Current border color of the active window clInactiveBorder Current border color of inactive windows clAppWorkSpace Current color of the application workspace clHighlight Current background color of selected text clHighlightText Current color of selected text clBtnFace Current color of a button face clBtnShadow Current color of a shadow cast by a button clGrayText Current color of text that is dimmed clBtnText Current color of text on a button clInactiveCaptionText Current color of the text on the title bar of an inactive window clBtnHighlight Current color of the highlighting on a button cl3DDkShadow Dark shadow for three-dimensional display elements cl3DLight Light color for three-dimensional display elements (for edges facing the light source) clInfoText Text color for tooltip controls clInfoBk Background color for tooltip controls Remember that other colors may still be used by giving an exact color specification in $$BBGGRR hex format: for example, $$007FFF is orange. Defining Classes ================ The Class..EndClass construct may be used to create classes that are implemented in script code. The classes must be defined using this construct before they are referred to with $New(): Class <class name> [extends <parent class name>] <class definition> EndClass <class name> is the name that will be used to refer to the new class. If a parent class name is specified, the class will be a subclass of the specified parent class (which must have been previously defined with Class..EndClass; user-defined classes cannot derive from VCL classes). <class definition> consists of zero or more method or property definitions. Method and property definitions can be prefixed with access specifiers that control who can access the method or property: 'private' means that it can only be used by methods of the same class, 'protected' means that it can only be used by methods of the same class or subclasses, and 'public' (the default) means that it can be used anywhere. Method definitions ------------------ Method <name> <code> EndMethod Creates a new method with the specified name and code. The code will be called whenever the method is called, whether it is called as a command or a function. $0 contains the object handle, a period, and the method name, and it will be prefixed with a % if the method was called as a function. The parameters will be passed in $1, $2, and so on, like an alias call. Two special method names can be used: <Create> and <Destroy>. The <Create> method will be called when an instance of this class is created with $New(). The parameters after the class name in $New() will be passed in as $1, etc. The <Destroy> method will be called when an instance of this class is destroyed, and the parameters will be any extra text that was given after the object handle (e.g., the "foo" in "Destroy $obj foo"). Every method has two special variables available: $Caller, which contains the handle of the object responsible for calling this method (or -1 if the method was called from an alias, event, or menu item); and $Self, which contains the handle of the object whose method was called. $Caller will always be the same as $Self when the method being called is <Create>, <Destroy>, or a property reader/writer. Property definitions -------------------- Property <name> [read <reader>] [noread] [write <writer>] [nowrite] Creates a new property with the specified name. If a reader is supplied, it should be the name of a method that will be used to retrieve the property. Similarly, if a writer is supplied, it should be the name of a method that will be used to set the property. The special value "Nop" can be used as a reader or writer to show that other objects cannot read or write the property. "noread" and "nowrite" are equivalent to "read Nop" and "write Nop", respectively. If a reader is supplied, the method will be called whenever another object tries to retrieve the property with $Prop(). The method will have one parameter: the name of the property ($1). This makes it possible to use the same reader for multiple properties. If a writer is supplied, the method will be called whenever another object tries to set the property with @P. The method will have two parameters: the name of the property ($1) and the value being set ($2-). If no reader or writer is supplied for a property, the property will be read or written like a variable: the value will be retrieved from or stored in an internal field in the object instance. Readers and writers are only used by other objects: an object always directly accesses its own properties as if they were variables. In other words, $prop($Self.PropName) and '@p $Self.PropName = Value' pretend that no reader or writer was set for the property. Here's an example of when this might be useful: Class TMyButton Private Property TheButton Property Caption write SetCaption Private Method <Create> @l $btn = $new(TButton ownedby $someform position 5,5,30,10) @p $Self.TheButton = $btn @p $btn.Caption = My button @p $Self.Caption = My button EndMethod Private Method <Destroy> Destroy $prop($Self.TheButton) EndMethod Private Method SetCaption @p $prop($Self.TheButton).Caption = $2- @p $Self.Caption = $2- EndMethod EndClass Now the Caption property of TMyButton objects will mirror the Caption of the associated TButton. TMyButton's writer for Caption copies the value to the TButton, then caches it in its own Caption field. When the TMyButton's Caption is read, the value is fetched directly from the field. Mapping Objects =============== The host application can allow OVS scripts access to its forms and controls. Use the $MapObject() function to do this: $MapObject(FormName:ControlName) or $MapObject(FormName). The function returns an object handle if mapping succeeds, or -1 if it fails. The object handle can be used just like a handle created with $New(). To release a mapped object handle without destroying the object, use the UnmapObject command: UnmapObject $obj Other OVS Commands/Functions ============================ AddToSetProp <object>.<property> <items> Reads <property> from <object> (the multiple-indirection syntax is allowed). If it contains a set, or a string that looks like a set, <items> is added (just like with $AddToSet(<propvalue> <items>)) and then stored back into the property. This function is only enabled when set functions are enabled. $ClassOf(<object>) Returns the name of the class that <object> belongs to, or "TUnknown" if the object handle is invalid. Inherited <methodname> [<parameters>] When used in a user-defined class's method, this calls the named method from the superclass. If <parameters> is omitted, the method will be called with the parameters given to the current method. This is most commonly useful in the <Create> method, to ensure that the superclass's constructor is called: Method <Create> Inherited <Create> // class-specific initialization goes here EndMethod $Inherited(<methodname> [<parameters>]) The same as 'Inherited <methodname> <parameters>', but automatically inserts the result. Use this when the inherited method is a function and its value is needed by the subclass's method. $IsA(<object> <class>) Returns true if <object> is a member of <class>, or a class that derives from <class>. $MapProp(<object>.<property>) Used only with object-type properties, maps the stored object to an OVS handle and returns it. A new handle is created even if the object is already available by a different handle. Use UnmapObject when the handle is no longer needed. If the property does not hold an object type, or if no object is currently stored, the result is -1. For example: @l $myfont = $MapProp($mylabel.Font) @p $myfont.Name = Arial Black @p $myfont.Size = 36 UnmapObject $myfont $ParentClassOf(<classname>) Returns the name of the named class's parent class, "TUnknown" if the class name is unknown, or "TOVSObject" if the class is a user-defined class with no parent. $ParentClassOf(<object>) The same as $ParentClassOf($ClassOf(<object>)). RemoveFromSetProp <object>.<property> <items> Reads <property> from <object> (the multiple-indirection syntax is allowed). If it contains a set, or a string that looks like a set, <items> is removed (just like with $RemoveFromSet(<propvalue> <items>)) and then stored back into the property. This function is only enabled when set functions are enabled. Exposed VCL Class Reference =========================== This section documents the VCL classes that VSInterp exposes to the script. Visible Controls ---------------- Common to most visible controls Properties: Top (integer) The top of the control, in pixels down from the top of the control's container (or from the top of the screen, for forms). Left (integer) The left of the control, in pixels from the left of the control's container (or the left edge of the screen, for forms). Height (integer) The height of the control, in pixels. Width (integer) The width of the control, in pixels. Align (enumeration) Determines how the control moves itself. The default is alNone, which makes it stay where it's put. Also available are alTop and alBottom, which make it move to the top or bottom of its container and expand to the width of the container; alLeft or alRight, which make it move to the left or right of its container and expand to the height of the container; and alClient, which makes it fill all the available space in its container. Visible (Boolean) Determines whether the control is visible on the screen. Font (object) Contains a TFont object that describes how text will be drawn on the control. PopupMenu (object) Holds the popup menu that will be displayed when the user right-clicks on the control. Color (color) The background color of the control. Hint (string) The text that appears in the status bar and pop-up hint window when the mouse is held over the control. If the string contains a vertical bar (as in "OK|Accept these changes"), the part before will be shown as a pop-up hint, and the part after will be shown in the status bar. Methods: SetFocus Causes the control to become activated. BringToFront Causes the control to appear in front of other controls. Invalidate Causes the control to be redrawn next time the program is idle. Refresh Causes the control to be redrawn immediately. Events: (not all controls support these) OnClick Called when the control is clicked or otherwise chosen. This is a notify event. OnDblClick Called when the control is double-clicked. This is a notify event. OnEnter/OnExit Called when the control gains or loses the focus. These are notify events. OnMouseDown Called when the mouse is pressed down over the control. Available variables are $Button (mbLeft, mbRight, or mbMiddle), $Shift (set of ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, and/or ssDouble), and $X and $Y (coordinates of mouse, relative to the control's top left). OnMouseUp Called when the mouse is released over the control. Same variables as OnMouseDown. OnMouseMove Called when the mouse moves over the control. Available variables are $Shift, $X, and $Y, which are the same as in OnMouseDown. OnKeyUp/OnKeyDown Called when a key is pressed or released while the control has the focus. Available variables are $Shift (same on OnMouseDown) and $Key, which is an integer holding the scan code of the key (the scan code is not the same as the ASCII code). $Key can be changed (with @L, not @) to pretend that another key was pressed. Set $Key to 0 to ignore the key. OnKeyPress Called when a key with an ASCII equivalent is pressed while the control has the focus. The only special variable is $Key, which contains the character as a string. $Key can be changed (with @L) to pretend that another key was pressed. Set $Key to $null to ignore the key. TButton This control is a standard Windows push button that can be clicked. Properties: Caption (string) The text that appears on the button. If there is an ampersand (&) in the text, the next character will be underlined, and pressing alt with that character will be equivalent to clicking the button. Use two ampersands (&&) to make a literal ampersand appear. Cancel (Boolean) Determines whether pressing Escape on the form is equivalent to clicking the button. Each form can only have one cancel button. Default (Boolean) Determines whether pressing Enter on the form is equivalent to clicking the button. Each form can only have one default button. ModalResult (integer) When this has a nonzero value and the form holding the button was shown with ShowModal, clicking this button will cause the form to disappear and the form's ShowModal method to return this value. TEdit This control is a standard Windows edit box. Properties: AutoSelect (Boolean) Determines whether the text in the edit box will automatically be selected when the edit box gains the focus. CharCase (enumeration) Determines how the case of the text is changed automatically. When this is set to the default value (ecNormal) the case is left as it is typed. When set to ecLowerCase or ecUpperCase, the text is automatically changed to lower or upper case. MaxLength (integer) Limits the number of characters the user can type. A value of 0 means no limit. PasswordChar (integer) Determines whether the text appears masked out with a special character. Set this to the ASCII code of a character to cause that character to appear instead of the actual contents of the control, or 0 to disable masking. ReadOnly (Boolean) Determines whether the text can be edited by the user. If this property is true, the user can read and select the text, but not change it. SelLength (integer) The number of characters in the selection. SelStart (integer) The first selected character, where 0 is the first character. If there is no selection, this returns the position of the cursor. SelText (string) The text in the selection. Read this to retrieve the selection, or set it to change the selection. Text (string) The entire contents of the edit box. Events: OnChange Called whenever the contents of the edit box change. The Text property has already been changed by the time this is called. This is a notify event. TListBox This is a standard Windows list box. Properties: ItemIndex (integer) The index of the currently selected item in the Items list, or -1 if no item is selected. Items (object) Contains a TStrings object holding the items of the list box. MultiSelect (Boolean) Determines whether the list box will allow more than one item to be selected at a time. Sorted (Boolean) Determines whether new items that are added to Items will automatically be sorted. Methods: GetSelected(<num>) Returns 1 if item number <num> (starting at zero) is currently selected, or 0 otherwise. SetSelected <num> <value> Unselects item number <num> if value is nonzero, or selects it otherwise. Events: OnClick This is called whenever an item is selected or unselected. TForm This represents a window. Properties: BorderIcons (set) Determines which icons appear in the form's title bar. Possible members are biSystemMenu, biMinimize, biMaximize, and biHelp. BorderStyle (enumeration) Sets the style of the form's border. Possible values are bsDialog, bsSingle, bsNone, bsSizeable, bsToolWindow, and bsSizeToolWin. FormStyle (enumeration) Sets the style of the form. The default is fsNormal, which is a regular form. Other values are fsMDIChild, which makes the form an MDI child window (it must have been set ownedby an MDI parent when it was created); fsMDIForm, which makes the form an MDI parent; and fsStayOnTop, which makes the form stay on top of other forms. Icon (object) Contains a TIcon object that holds the form's icon. Menu (object) Contains a TMainMenu object that holds the form's menu bar. WindowMenu (object) Contains a TMenuItem object that holds the form's Window menu. This is only meaningful if the form is an MDI parent. WindowState (enumeration) Sets the display state of the form. This can be wsNormal, wsMinimized, or wsMaximized. Methods: ArrangeIcons Arranges the minimized children of an MDI parent. Cascade Cascades the children of an MDI parent. ShowModal Shows the form and does not return control (or let other forms activate) until the user clicks a button on the form that has a nonzero ModalResult. Tile Tiles the children of an MDI parent. Events: OnActivate Called when the form becomes active. OnClose Called when the form is closing. Set (@L) $Action to caNone (don't close), caHide (hide the form), caFree (destroy the form), or caMinimize. OnCloseQuery Called when the form is about to close. Set $CanClose to False to prevent the form from closing. OnDeactivate OnHide OnPaint OnShow TLabel This is a standard Windows text label. Properties: Alignment (enumeration) Controls the horizontal placement of text on the label. Possible values are taLeftJustify (the default), taRightJustify, and taCenter. AutoSize (Boolean) Determines whether the label will automatically adjust its size to hold all the text. Caption (string) The text that appears on the label. If ShowAccelChar is true, this can contain ampersands just like TButton's Caption property. FocusControl (object) Holds the control that is activated when the user presses Alt and the underlined character in the label's caption when ShowAccelChar is true. ShowAccelChar (Boolean) Determines whether an ampersand causes the next character in the caption to be underlined and act as an accelerator character. Transparent (Boolean) Determines whether the label is transparent and allows anything underneath it to show through. WordWrap (Boolean) Determines whether text that is too wide to fit in the label automatically wraps to the next line. TStaticText This is just like TLabel, but it's a windowed control instead of a graphical control. Sometimes TLabel won't work correctly because it isn't windowed: for example, it won't appear when placed on an MDI parent form. TCheckBox This is a standard Windows check box. Properties: Alignment (enumeration) Determines whether the caption appears to the left or right of the check box. If this property is taRightJustify (the default) the caption is to the right. If it's taLeftJustify, the caption is to the left. AllowGrayed (Boolean) Determines whether the check box can have a grayed state. Checked (Boolean) Determines whether the check box is checked. This is false if the box is unchecked or grayed. State (enumeration) Determines the state of the check box: cbUnchecked, cbChecked, or (if AllowGrayed is true) cbGrayed. Events: OnClick Called when the box's state changes. TRadioButton This is a standard Windows radio button. By default, only one radio button in a given container can be selected at once. See TRadioGroup for an easy way to make a new group of radio buttons. Properties: Alignment (enumeration) Same as TCheckBox's Alignment property. Checked (Boolean) Determines whether the radio button is checked. Set this to true to select this button and unselect all the others in the group. Events: OnClick Called when the button is selected. TRadioGroup This represents a group of radio buttons that function together. It appears like a TGroupBox with several radio buttons inside. Properties: Columns (integer) The number of columns of radio buttons shown. The default is 1; values can range from 1 to 16. ItemIndex (integer) The index of the currently selected button in the Items list, or -1 if no button is selected. Items (object) Contains a TStrings object holding the captions of the radio buttons. Adding values to this causes more buttons to be created. Events: OnClick Called when one of the radio buttons is selected. TMemo This is a standard Windows multiline edit control. Properties: Alignment (enumeration) Same as TLabel's Alignment property. Lines (object) Contains a TStrings object holding the lines of the edit control. ScrollBars (enumeration) Determines which scroll bars are visible. Values are ssNone, ssHorizontal, ssVertical, and ssBoth. SelLength (integer) The number of characters in the selection. SelStart (integer) The first selected character, where 0 is the first character. If there is no selection, this returns the position of the cursor. SelText (string) The text in the selection. Read this to retrieve the selection, or set it to change the selection. WantReturns (Boolean) Determines the handling of return keystrokes. If this is true, pressing return will start a new line in the edit control; otherwise, it will activate the default button on the form (ctrl-enter will start a new line anyway). WantTabs (Boolean) Determines the handling of tab keystrokes. If this is true, pressing tab will insert a tab character; otherwise, it will move the focus to the next control. WordWrap (Boolean) Determines whether text that is too wide to fit into the visible area of the control should be wrapped onto the next line. Wrapping text this way doesn't insert return characters; the wrapping is only cosmetic. Events: OnChange Called whenever the contents of the control change. The Lines property has already been changed by the time this is called. This is a notify event. TPanel This is a panel that can contain other controls. Properties: Alignment (enumeration) Same as TLabel's Alignment property. BevelInner (enumeration) Determines what style the inner edge of the bevel is displayed in. Values are bvNone (no inner edge), bvLowered, and bvRaised. BevelOuter (enumeration) Same as BevelInner, but controls the outer edge. BevelWidth (integer) Controls the width of the individual bevel edges. BorderWidth (integer) The width in pixels of the border. Events: OnResize Called whenever the panel's size changes. This is a notify event. TBitBtn This is a push button that can include a bitmap on its surface. It derives from TButton, so everything there also applies. Properties: Glyph (object) Contains a TBitmap object holding the bitmap on the button's face. Kind (enumeration) Allows the button to quickly change forms. Values are bkCustom, bkOK, bkCancel, bkHelp, bkYes, bkNo, bkClose, bkAbort, bkRetry, bkIgnore, bkAll. Each value changes the button's caption, glyph, and ModalResult; except bkCustom, which allows arbitrary values to be chosen for those properties. Layout (enumeration) Determines where the glyph appears. Values are blGlyphLeft, blGlyphRight, blGlyphTop, and blGlyphBottom. Margin (integer) Determines the number of pixels between the edge of the bitmap and the edge of the button. If this is -1 (the default), the image and text are centered. NumGlyphs (integer) Sets the number of images contained in the Glyph property. If a bitmap is loaded there containing more than one image side-by-side (which must all be the same size), set this property to tell the button how many images there are. The first one should be the bitmap for the up position, the second should be the disabled bitmap, and the third should be for the down positon (while the mouse is held over the control). Spacing (integer) Determines the number of pixels between the edge of the bitmap and the text. TScrollBar This is a free-standing scroll bar. Properties: Kind (enumeration) Sets the orientation of the scroll bar. Values are sbHorizontal and sbVertical. LargeChange (integer) Determines how much the Position property changes when the user clicks the scroll bar on either side of the thumb or presses PgUp/PgDn. Min/Max (integer) Sets the minimum and maximum value the Position property can take. Position (integer) Determines the current position of the thumb. SmallChange (integer) Determines how much the Position property changes when the user clicks the arrow buttons or presses the arrow keys. Events: OnChange Called after the value of Position changes. This is a notify event. TGroupBox This is a standard Windows group box. It can contain other controls. Properties: Caption (string) The text that appears at the top of the group box. TComboBox This combines an edit box with a scrollable list. Properties: DropDownCount (integer) Determines how many items will fit in the drop-down list part without scrolling. ItemIndex (integer) The index of the currently selected item in the Items list, or -1 if no item is selected. Items (object) Contains a TStrings object holding the items of the drop-down list. MaxLength (integer) Limits the number of characters the user can type. A value of 0 means no limit. SelLength (integer) The number of characters in the selection. SelStart (integer) The first selected character, where 0 is the first character. If there is no selection, this returns the position of the cursor. SelText (string) The text in the selection. Read this to retrieve the selection, or set it to change the selection. Sorted (Boolean) Determines whether the drop-down list is alphabetized. Style (enumeration) Determines the display style of the combo box. Values are csDropDown (drop-down list and edit box), csSimple (edit box with a permanent list box below), and csDropDownList (drop-down list without edit box). Text (string) The text displayed in the edit box. Events: OnChange Called when the text displayed in the edit box changes. This is a notify event. OnDropDown Called when the user opens the drop-down list by clicking the arrow at the right of the control. This is a notify event. TProgressBar This is a standard Windows progress bar. Properties: Min/Max (integer) Sets the minimum and maximum values the Position property can take. Position Sets the current position of the progress bar. TMainMenu This is the menu bar of a form. Set the form's Menu property to a TMainMenu control to give it a menu bar. Properties: Items (object) Contains a TMenuItem object that holds the items of the menu bar. TPopupMenu This is a standard popup menu. Set the PopupMenu of another control to a TPopupMenu control to have the popup menu appear when the user right-clicks the other control. Properties: Alignment (enumeration) Sets the corner of the popup menu that will be under the mouse when the menu pops up. Values are paLeft (top-left corner), paCenter (center of the top edge), and paRight (top-right corner). AutoPopup (Boolean) Determines whether the menu will pop up automatically when the user right-clicks on an associated control. If this is false, the popup menu will only be displayed by the Popup method. PopupComponent (object) Contains the last control that was responsible for popping up the menu. Methods: Popup <X> <Y> Displays the menu at the given coordinates (relative to the top-left corner of the screen). Events: OnPopup Called before the menu is displayed. This is a notify event. TMenuItem This describes the properties of an item in the menu. A TMenuItem object can contain other menu items to create submenus - use the Add method. Properties: Break (enumeration) Determines whether the menu item starts a new column in the menu. Values are mbNone (the default - no break), mbBarBreak (starts a new column with a vertical bar in between), and mbBreak (starts a new column with only space in between). Caption (string) The text of the menu item. Ampersands can appear here with the usual effect. Checked (Boolean) Determines whether a check box appears next to the item. Default (Boolean) Determines whether the item appears in boldface and is executed when its parent item is double-clicked. Enabled (Boolean) Determines whether the item is enabled. GroupIndex (integer) Identifies a group of radio button menu items. RadioItem (Boolean) Determines whether the item appears like a radio button when it is checked. Only one item with the same GroupIndex property can be checked at a time. Visible (Boolean) Determines whether the item appears in the menu. Methods: Add <object> Adds the object (which must be a TMenuItem) to the end of the menu. Delete <num> Deletes the numbered item from the menu, where 0 is the first item. IndexOf(<object>) Returns the position of the item in the menu. Insert <num> <object> Inserts the item into the menu at the given numbered position. Remove <object> Removes an item and all of its subitems from the menu (but doesn't destroy them). Events: OnClick Called when the menu item is chosen. This is a notify event. TListView This is the standard Windows list view control, as seen in Explorer folder windows (as well as ViRC's ban list and /who window). There are four views: large icon, small icon, list, and report (details). Each item that appears in the list view is represented by a TListItem object. Properties: BorderStyle (enumeration) Determines whether a border is drawn around the control. Valid values are bsNone and bsSingle. Checkboxes (Boolean) Determines whether a checkbox appears next to each list item. If an item's box is checked, the item's Checked property will be True. ColumnClick (Boolean) Determines whether the column headers can be clicked like buttons (when ViewStyle = vsReport). Columns (TListColumns) The collection of list columns for report view. Create new columns with $ListView.Columns.Add(). FlatScrollBars (Boolean) Determines whether the control's scroll bars are drawn flat or with 3D bevels. GridLines (Boolean) Determines whether grid lines are drawn in list and report views. HideSelection (Boolean) Determines whether the selection is hidden when another control has the focus. HotTrack (Boolean) Determines whether the user can select items by pausing the mouse over them. HotTrackStyles (set) Changes options for hot tracking. Possible members are htHandPoint (mouse cursor turns into a hand), htUnderlineCold (underline all untracked items), and htUnderlineHot (underline the tracked item). HoverTime (Integer) How long the user has to pause the mouse to select an item, in milliseconds. -1 uses the system default. ItemFocused (TListItem) The item that is currently focused, or "nil" if no item is focused. Items (TListItems) The collection of items in the list. Create new items with $ListView.Items.Add() LargeImages (TImageList) The bitmaps to use for large icon view. Set an item's ImageIndex property to assign it one of these. MultiSelect (Boolean) Determines whether the user can select more than one item at a time. OwnerDraw (Boolean) Determines whether the OnDrawItem event is called to draw list items. ReadOnly (Boolean) Determines whether the user is able to edit item captions. RowSelect (Boolean) Determines whether the user selects entire rows at once in report view. SelCount (Integer) The number of selected items. Selected (TListItem) The item that is currently selected, or "nil" if no item is selected. SmallImages (TImageList) The bitmaps to use for small icon view. Set an item's ImageIndex property to assign it one of these. StateImages (TImageList) The bitmaps to use for items' StateIndex properties. ViewStyle (enumeration) The current view mode. Possible values are vsIcon, vsSmallIcon, vsList, and vsReport. Methods: AlphaSort Sorts the items in alphabetical order by caption, or by calling the OnCompare event with $Data empty if an OnCompare handler is set. Arrange <type> Arranges the icons. For <type>, 0 = align along the bottom, 1 = align along the left, 2 = align along the right, 3 = align along the top, 4 = default alignment, 5 = snap to grid. CustomSort <text> Sorts the items by calling the OnCompare event. <text> is passed to the event as $Data. GetColumn() Returns the i'th item from the Columns collection. Events: OnChange Called when an item's properties change. $Item is the item and $Change is ctText if the caption changed, ctImage if the image changed, or ctState if the Cut, Focused, or Selected property changed. OnChanging Called when an item's properties are about to change. $Item is the item, $Change is as above, and the event should set $AllowChange to 0 (don't allow the change) or 1 (allow it). OnColumnClick Called when the user clicks a column header, if the ColumnClick property is True. $Column is the column object that was clicked. OnColumnRightClick Called when the user right-clicks a column header. $Column is the column object, $X and $Y are the click location in client coordinates. OnCompare Called to compare items for sorting. $Item1 and $Item2 are the item objects being compared, $Data is the parameter given to CustomSort, and the event should set $Compare to a negative value if $Item1 comes first, a positive value if $Item2 comes first, or 0 if the items are equal. $Data is empty if the event is being called by AlphaSort. OnDeletion Called when an item ($Item) is about to be deleted. OnEdited Called when the user has changed an item's caption. $Item is the item and $Text is the new value. Change $Text to override the user's value. OnEditing Called when the user is about to edit an item's caption. $Item is the item, and the event should set $AllowEdit to 0 (don't allow editing) or 1 (allow). OnInfoTip Called when the hint is about to be displayed. $Item is the item under the mouse and $InfoTip is the default hint. Change $InfoTip to display a different hint. OnInsert Called when a new item ($Item) is being inserted. OnSelectItem Called when an item is being selected or unselected. $Item is the item, $Selected is 0 if the item was unselected or 1 if it was selected. TListColumn This represents a column in a list view. Columns are only shown when ViewStyle is vsReport. Properties: Alignment (enumeration) Determines the horizontal placement of text in the column. Possible values are taLeftJustify, taRightJustify, and taCenter. AutoSize (Boolean) Determines whether the column automatically resizes to the width of its text. Caption (string) The caption shown at the top of the column. ImageIndex (Integer) The index into the list view's SmallImages list of an image to display in the column, or -1 for none. MaxWidth (Integer) The largest that the user will be able to resize the column. MinWidth (Integer) The smallest that the user will be able to resize the column. Width (Integer) The width of the column. Set this to -1 to resize the column to the width of the text, or -2 to resize the column to the width of its caption. TListItem This represents an item in a list view. Properties: Caption (string) The text displayed for the item. Checked (Boolean) Determines whether the item's box is checked when the list view's Checkboxes property is True. Cut (Boolean) Determines whether the item appears dimmed like a file being cut in Explorer. Focused (Boolean) Determines whether the item has input focus. ImageIndex (Integer) The index into the list view's LargeImages or SmallImages lists for this item, or -1 to display no image. Indent (Integer) The number of small image widths this item is indented for report view. Index (Integer) The index of this item in the list view's Items collection. Read-only. Left (Integer) The horizontal position of this item for icon views. ListView (TListView) The list view that contains this item. Read-only. OverlayIndex (Integer) The index into the list view's StateImages list of an image that should be drawn over the item's icon, or -1 for no overlay. Selected (Boolean) Determines whether the item is selected. StateIndex (Integer) The index into the list view's StateImages list of an image to display to the left of the item's icon, or -1 for no state image. SubItems (TStrings) A list of strings for subitems in report view. The first column is the item's caption, the second column is the first subitem, the third column is the second subitem, and so on. Top (Integer) The vertical position of this item for icon views. Methods: CancelEdit Ends editing of the caption and discards any changes made by the user. EditCaption Puts the item into edit mode, allowing the user to change the caption. GetSubItemImage() Returns the index into the list view's SmallImages list of an image to display next to the i'th subitem in report view, or -1 for none. MakeVisible <partial> Scrolls the list item into view. If <partial> is 0, the item will be scrolled if it's not completely visible; if <partial> is 1, the item won't be scrolled if it's already partially visible. SetSubItemImage <index> Sets the i'th subitem's image. Invisible Controls ------------------ TStrings This is used by several controls to hold a list of strings. It contains a dynamically growing list with items numbered starting at zero. This control cannot be created; use TStringList for a standalone string list. Properties: CommaText (string) Contains all the strings in the list joined together with commas. Any items with spaces, commas, or quotes will be surrounded in double quotes, and any double quotes in the item will be repeated. Set this to change the entire list at once. Count (integer) Returns the number of strings in the list. Read-only. Text (string) Contains all the strings in the list joined together with carriage return/line feed pairs ($char(13)$char(10)). Set this to change the entire list at once. Methods: Add(<string>) Adds the string to the list and returns its index. Call this as a command if the index isn't needed. Assign <object> Assigns another object (which must be a TStrings) to this one. This list now contains the same strings as the other list. Clear Removes all the strings from the list. Delete <num> Deletes the numbered string from the list. Equals(<object>) Returns true if the other list contains the same strings in the same order as this one. Exchange <a> Exchanges strings numbered <a> and . Execute Executes the contents of the list as Versus code. GetAliasList Fills the string list with a list of all the names of aliases that have been created. Only enabled if the VSInterp is allowed to manage aliases. GetDirList <mask> Fills the string list with a list of all the directories matching <mask>. Only enabled if file commands/functions are enabled. GetFileList <mask> Fills the string list with a list of all the files matching <mask>. Only enabled if file commands/functions are enabled. GetString(<num>) Returns the string at the given position. IndexOf(<string>) Searches the list and returns the position where <string> appears, or -1 if it does not appear. IndexOfMask(<mask>) Returns the position of the first string that matches <mask>, or -1 if none match. IndexOfName(<string>) Searches the list and returns the position where <string> appears to the left of an equal sign, or -1 if it does not appear. Insert <num> <string> Inserts the string at the given position. LoadFromAlias <name> Loads the string list with the code of the named alias. Only enabled if the VSInterp is allowed to manage aliases. LoadFromFile <file> Loads the string list from the lines in the named file. Only enabled if file commands/functions are enabled. LoadFromList <list> Loads the string list from a Versus list so that each string in the list corresponds to an element of the Versus list. LoadFromSet <set> Loads the list from a set so that each string in the list is a corresponding item of the set. Move <from> <to> Moves the string at position <from> so that it occupies position <to>. SaveToAlias <name> Creates or replaces an alias with the given name, using the strings in the list as code. Only enabled if the VSInterp is allowed to manage aliases. SaveToFile <file> Saves the string list to the named file. Only enabled if file commands/functions are enabled. SaveToList() Returns the string list converted to a Versus list, where each item of the Versus list corresponds to a string in the list. SaveToSet() Returns the list converted to a set, where each item of the set is a corresponding string in the list. SetString <num> <string> Sets the string at the given position. TStringList This derives from TStrings to implement a standalone string list. Properties: Sorted (Boolean) Determines whether the strings in the list are automatically sorted, and the Add method inserts new strings in the correct alphabetical position. TTimer This fires an event repeatedly after a specified interval. Properties: Enabled (Boolean) Determines whether the timer is ticking. Interval (integer) The number of milliseconds that pass between event firings. Events: OnTimer Called every <Interval> milliseconds while the timer is enabled. This is a notify event. TIcon This represents an icon. Use this in a form's Icon property. Properties: Height/Width (integer) Return the height and width of the icon. Read-only. Methods: LoadFromFile <file> Loads an icon file from the disk into the object. TBitmap This represents a bitmap. Use this in a button's Glyph property. Properties: Height/Width (integer) Return the height and width of the bitmap. Read-only. Methods: LoadFromFile <file> Loads an bitmap file from the disk into the object. TFont This represents a font. Most visible controls have Font properties that hold TFont objects. Properties: Color (color) Specifies the color of the text. Name (string) Specifies the name of the font. Size (integer) Specifies the size of the font in points. Style (set) Specifies the style of the font. Possible members are fsBold, fsItalic, fsUnderline, and fsStrikeout. TListColumns This is the collection used by TListView to manage the columns. Properties: Count (Integer) Returns the number of columns in the collection. Read-only. Methods: Add() Creates a new column (TListColumn) and returns the object handle. Assign <obj> Copies all the items from <obj>, which must be a TListColumns. BeginUpdate Call this before making a lot of changes to the columns to reduce flicker. Clear Deletes all the columns. Delete Deletes the i'th column from the list. EndUpdate Call this when you are done making changes after BeginUpdate. IndexOf(<obj>) Returns the index of <obj> in the collection. Insert() Creates a new column at position and returns the object handle. GetItem() Returns the i'th column object. TListItems This is the collection used by TListView to manage the items. Properties: Count (Integer) Returns the number of items in the list. Read-only. Methods: Add() Creates a new item (TListItem) and returns the object handle. Assign <obj> Copies all the items from <obj>, which must be a TListItems. BeginUpdate Call this before making a lot of changes to the items to reduce flicker. Clear Deletes all the items. Delete Deletes the i'th item from the list. EndUpdate Call this when you are done making changes after BeginUpdate. IndexOf(<obj>) Returns the index of <obj> in the collection. Insert() Creates a new item at position and returns the object handle. GetItem() Returns the i'th item object. TImageList This holds a list of images for use with TListView. Properties: BkColor (color) The color used for the masked regions of images in the list, or clNone to draw transparently. BlendColor (color) The color to be combined with the images when they are being drawn to appear focused or selected, or clNone for no blend color, or clDefault for the system default. Count (Integer) Returns the number of images in the list. Read-only. Height (Integer) The height of images in the list. The list is cleared when this changes. Masked (Boolean) Determines whether the image list includes masks for transparent drawing. Width (Integer) The width of images in the list. The list is cleared when this changes. Methods: Add(<obj>) Adds <obj>, which must be a TBitmap, to the list. Returns the new index. Add(<obj> <mask>) Adds a bitmap to the list along with an associated mask for transparency, which must also be a TBitmap. Returns the new index. AddIcon(<obj>) Adds <obj>, which must be a TIcon, to the list. Returns the new index. Icons don't need a separate image for transparency. AddImages <obj> Copies all the images from <obj>, which must be a TImageList. Existing images are kept. AddMasked(<obj> <color>) Adds <obj>, which must be a TBitmap, to the list. A mask will be created making all the pixels with the given color transparent. Returns the new index. Assign <obj> Copies all the images from <obj>, which must be a TImageList. Existing images are discarded. Clear Deletes all the images. Delete Deletes the i'th image. Draw <obj> <x>,<y> Draws the i'th image at position (x,y) on <obj>, which must be a TCanvas. DrawOverlay <obj> <x>,<y> <o> Draws the i'th image with the o'th overlay on <obj>, which must be a TCanvas. Set up overlays with the Overlay method. GetBitmap <obj> Copies the i'th image into <obj>, which must be a TBitmap. GetIcon <obj> Copies the i'th image into <obj>, which must be a TIcon. Insert <obj> Inserts a bitmap into the list at position . Insert <obj> <mask> Inserts a bitmap with associated mask. InsertIcon <obj> Inserts an icon into the list at position . InsertMasked <obj> <color> Inserts a bitmap and generates a mask. Move <j> Moves an image from position to position <j>. Overlay <o> Allows image to be used as overlay <o> for DrawOverlay. <o> must be between 0 and 3. Replace <obj> Replaces image with a new bitmap. Replace <obj> <mask> Replaces image with a new bitmap and mask. ReplaceIcon <obj> Replaces image with a new icon. ReplaceMask <obj> <color> Replaces image with a new bitmap and generates a mask.